# Network issue

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# What should I do if I cannot connect to the network?

## Physical and data link layers (Ethernet cable/Wi-Fi/switch)

Symptom: After running **ip a**, the output does not show an IP address, or the network interface is shown as DOWN.

| **Common causes** | **Solutions** |
| --- | --- |
| Ethernet cable is loose or damaged | Reconnect the Ethernet cable and observe the Ethernet port LEDs. A steady green LED and a blinking yellow LED indicate data transmission. |
| Wi-Fi is disconnected or the signal is weak | Check the Wi-Fi configuration file (for example, */etc/wpa_supplicant.conf*), or run **nmcli dev wifi connect** to reconnect. |
| Switch or router port failure | Use a different switch port, or connect the two devices directly with an Ethernet cable (a static IP address must be configured) to rule out an upstream network issue. |
| Network interface driver is not loaded | Run **dmesg** \| **grep -i eth** or **lspci** to verify that the kernel has detected the network hardware. |

## Network layer (IP address and subnet mask)

Symptom: After running **ip a**, the output shows an IP address, but the gateway does not respond to ping requests.

| **Common causes** | **Solutions** |
| --- | --- |
| Incorrect IP address configuration (not on the same subnet) | Check **ip a** for the configured IP address and subnet mask (for example, /24), and ensure that the address is on the same subnet as the gateway (for example, 192.168.1.1). |
| IP address conflict (two devices use the same IP address) | Use an unassigned IP address, or enable automatic address assignment through DHCP (dhclient eth0). |
| DHCP failed to obtain an address | Check whether the DHCP service is running (**ps aux**\|**grep dhcp**), or manually configure a static IP address to rule out a DHCP server failure. |
| Default gateway is missing | Run **ip route show** and check for a *default via* entry. If none exists, add one manually: **ip route add default via 192.168.1.1**. |

## Transmission layer (firewall and ports)

Symptom: Ping requests succeed (the ICMP protocol is working), but services such as SSH and HTTP are inaccessible.

| **Common causes** | **Solutions** |
| --- | --- |
| Firewall (iptables/nftables) blocking traffic | Check the rules by running **iptables -L -n -v**. Temporarily disable the firewall for testing by running **systemctl stop firewalld** (or **iptables -F**). |
| Service port is not listening or the service is not running | Run **netstat -tulpn** \| **grep 22** to verify that the sshd process is listening. |
| Port is in use or the service is bound to the loopback address (127.0.0.1) | Check the service configuration and ensure that it listens on 0.0.0.0 (all interfaces) rather than 127.0.0.1 (loopback only). |

## Application layer (DNS resolution)

Symptom: The host at **8.8.8.8** responds to ping, but ping www.baidu.com fails because the domain name cannot be resolved.

| **Common causes** | **Solutions** |
| --- | --- |
| DNS server is not configured or is unreachable | Check */etc/resolv.conf* and ensure that nameserver 8.8.8.8 or nameserver 114.114.114.114 is configured. |
| Corrupted DNS cache | Run **systemd-resolve --flush-caches** (if the systemd-resolved service is used), or restart the network service. |
| Public DNS servers outside China are unreachable | Use a public DNS server in China (for example, 223.5.5.5 or 114.114.114.114) to work around possible network restrictions. |

Perform a quick diagnosis in the following order:

```bash
# 1. Check the status of all network interfaces (particularly whether they are UP and RUNNING)
ip addr show

# 2. Check the default gateway IP 
route show default

# 3. Ping the gateway (test reachability)
ping -c 4 <gateway_IP_address>

# 4. Check the current DNS configuration
cat /etc/resolv.conf

# 5. Test domain name resolution
nslookup baidu.com

# 6. Check whether iptables/nftables is filtering traffic
sudo iptables -L -n
sudo nft list ruleset
```

# How do I troubleshoot network issues?

See the preceding section for the troubleshooting procedure.

# What should I do if the Wi-Fi connection fails?

## Check the hardware and firmware

First, ensure that the system can correctly detect the Wi-Fi module.

- Verify the Wi-Fi module: Refer to the smart single-board computer hardware manual and verify the Wi-Fi module model and antenna connection.

- Check driver loading: Run **iw dev** in the terminal and check whether the output contains a wlan0 interface. If there is no output, the driver may not be loaded.

- Check firmware loading: Run **dmesg**|**grep -i firmware** and check for firmware-loading errors (for example, failed to load).

- Verify the Wi-Fi mode: Some modules must first be set to STA (station) mode.

## Check the network interface and scan for networks

If the hardware is operating correctly, check whether the system can detect nearby wireless networks.

- Check the interface status: Run **ip addr show wlan0** and verify that the interface status is UP. If it is DOWN, run **sudo ip link set wlan0 up** to enable it manually.

- Scan for available networks: Run **sudo iw dev wlan0 scan**|**grep SSID** to scan for nearby Wi-Fi networks. If there is no output, there may be a driver or antenna issue.

- Use NetworkManager (if installed): Run **nmcli dev wifi list** to scan for networks.

## Check the connection configuration

If a network is detected but the connection fails, the configuration is usually the cause.

- Verify the SSID and password: An incorrect SSID or password is the most common cause. Verify that both are entered with the correct case.

- Check the encryption method: If wpa_supplicant is used, ensure that its configuration matches the router's encryption method (for example, WPA2-PSK).

- Check the wpa_supplicant service: Run **ps -ef | grep wpa_supplicant** to verify that the service is running.

- Check the Wi-Fi frequency band: Verify that the smart single-board computer supports the frequency band in use (for example, 2.4 GHz or 5 GHz).

## Check IP address assignment

If the connection succeeds but internet access is unavailable, the IP address configuration is usually the cause.

- Check the IP address: Run **ip addr show wlan0** and check whether a valid IP address (not 169.254.x.x) has been obtained.

- Obtain an IP address manually: Run **sudo dhclient wlan0** or **sudo udhcpc -i wlan0** to request an address manually.

- Check the DHCP service: Verify that the router's DHCP service is enabled and that its address pool is not exhausted.

# How do I configure a static IP address for Ethernet?

## Configure a temporary address with the ip command (takes effect immediately and is lost after a restart)

```bash
# 1. Check the network interface name (usually eth0 or enp*)
ip addr show

# 2. Add a static IP address to the network interface (for example, 192.168.1.100/24)
sudo ip addr add 192.168.1.100/24 dev eth0

# 3. Enable the network interface (if it was previously down)
sudo ip link set eth0 up

# 4. Add the default gateway (for example, 192.168.1.1)
sudo ip route add default via 192.168.1.1

# 5. Configure DNS (requires editing /etc/resolv.conf)
echo "nameserver 8.8.8.8" | sudo tee -a /etc/resolv.conf
echo "nameserver 114.114.114.114" | sudo tee -a /etc/resolv.conf
```

## Persist the configuration with systemd-networkd

### Create or edit the network interface configuration file

```bash
sudo nano /etc/systemd/network/20-eth0-static.network
```

### Enter the following content

```bash
[Match]
Name=eth0

[Network]
Address=10.66.82.100/23
Gateway=10.66.82.1
DNS=8.8.8.8
DNS=114.114.114.114

```

### Restart the network service

```bash
sudo systemctl restart systemd-networkd
```

# How do I check network bandwidth?

Check the negotiated physical link speed:

```bash
ethtool eth0 | grep -E "Speed|Duplex"
```